<?php
// $Id: cronjobs.inc 451 2017-10-22 09:13:27Z east $

/**
 * @file 自定义计划任务
 *  通过 hook_cronjobs() 定义的计划任务，可以灵活设置执行时间
 *  这种方式通常用于数据采集、挖掘等操作，每个任务必须对应模块 scripts 目录中的一个 php 文件
 *  cron.inc 在执行时，将调用 php 运行该文件，单独生成一个进程，便于管理，且减少相互影响
 */

/**
 * @Implement of hook_cronjobs()
 */
function system_cronjobs() {
  $cronjobs = array();

  // 定义一个任务，任务名称为 system  
  // 可通过 timestamp['system'] 获取本任务上一次执行时间，可能为 0
//  $cronjobs['system'] = array(
//    'name' => t('system', '系统任务'), // 显示名，必需
//    
//    // 可选，对应的脚本，该脚本必须位于模块的 scripts 目录，如：system/scripts，将调用 php 执行该脚本
//    'script' => 'system.inc',
//
//    // 可选，回调的函数，param 参数将传递给该函数。
//    // 执行失败返回 false，成功返回不为 false 的任何值
//    //'call_func' => '',
//    // 回调函数执行成功，则调用本函数
//    //'success_func' => '',
//
//    //'param' => array('date' => 20120102, 'id' => 'name'), // 可选参数，数据类型自定义。将做为参数传递给 scripts
//    //'minHour' => 13, // 可选参数，设置最小时间，当前小时必须大于该数字，才启动任务
//    //'maxHour' => 13, // 可选参数，与最小时间相反
//    'year' => '*', // 年，每一年
//    'month' => '*', // 月，每一月
//    'day' => '*', // 日，每一天
//    //'day' => '*/5', // 每 5 天
//    //'day' => '12', // 每月 12 号
//    //'minute' => '5', // 分，0-59
//    'hour' => '*', // 每小时执行
//    'minute' => '*/10', // 每 10 分钟执行一次
//    'weight' => 100, // 执行优先级，默认为 0，若非必要，勿自定义
//    //'timeout' => 3600, // 超时时间，若超过此时间未完成，则取消任务。默认不检查超时
//
//    // 不检查运行状态，直接启动任务，默认情况下，将检查是否有相同的任务在运行。若设置为 no，有可能造成任务阻塞
//    //'check_status' => 'no',
//  );

  /**
   * 以上 system 任务，等同于 5 * * * * php {$path}/test.inc --date 20120102 --id 100
   * 以这种 Dida 内部方式实现，比直接在系统 crontab 中添加任务的好处在于：
   *  1、统一管理，Dida 可将所有模块的任务统一调度，根据系统负载，其它任务的执行情况来合理安排；
   *  2、便捷，管理员只需要添加一条 php cron.inc 即可，省去繁琐的操作
   * 因此，建议所有模块开发者，均使用此种方式实现计划任务 
   *
   */

  // 分析所有模块在 hook_cronjobs 中定义的任务，将当前需要执行的任务写入 cron 表
  $cronjobs['system'] = array(
    'name' => t('system', '计划任务解析'),
    'script' => 'system.inc',
    'year' => '*',
    'month' => '*',
    'day' => '*',
    'hour' => '*',
    'minute' => '*',
    'weight' => 100,
    'check_status' => 'no',
  );

  // 存在于 cron 表中，却没有在 hook_cronjobs() 中定义的任务，使用此任务以让其于后台执行
  $cronjobs['cron_default_script'] = array(
    'name' => t('system', '通用任务脚本'),
    'script' => 'cron_default_script.inc',
    'year' => '2599',
    'month' => '*',
    'day' => '*',
    'hour' => '*',
    'minute' => '*',
    'check_status' => 'no',
  );

  // 将 cron 表中已经执行完成的记录，迁移到 cron_history 表，以提高 cron 表的读写效率
  $cronjobs['cron_history'] = array(
    'name' => t('system', '历史任务迁移'),
    'script' => 'cron_history.inc',
    'year' => '*',
    'month' => '*',
    'day' => '*',
    'hour' => '*',
    'minute' => '*/10',
    'timeout' => 480, // 超时设置
    'check_status' => 'ok',
  );

  // 若同时启用多个服务器，应在每个服务器上运行本任务
  $cronjobs['cron_check'] = array(
    'name' => t('system', '任务检查'),
    'script' => 'cron_check.inc',
    'param' => array('type' => 'update'),
    'year' => '*',
    'month' => '*',
    'day' => '*',
    'hour' => '*',
    'minute' => '*',
    'weight' => 90,
    'check_status' => 'ok',
  );

  $cronjobs['cron_kill'] = array(
    'name' => t('system', '任务清理'),
    'script' => 'cron_check.inc',
    'param' => array('type' => 'kill'),
    'year' => '*',
    'month' => '*',
    'day' => '*',
    'hour' => '*',
    'minute' => '*/5',
    'check_status' => 'ok',
  );

  // 执行所有模块在 hook_cron 中定义的任务
  $cronjobs['cron_default_function'] = array(
    'name' => t('system', '执行 hook_cron'),
    'call_func' => '_cron_function',
    'year' => '*',
    'month' => '*',
    'day' => '*',
    'hour' => '*',
    'minute' => '*/10',
    'check_status' => 'no',
  );

  $cronjobs['system_version_update'] = array(
    'name' => t('system', '检查系统更新'),
    'call_func' => 'system_status_update',
    'param' => 'cron',
    'year' => '*',
    'month' => '*',
    'day' => '*',
    'hour' => '1',
    'minute' => '1',
    'check_status' => 'ok',
  );

  return $cronjobs;
}
